Autogenerated HTML docs for v1.7.11-rc2
diff --git a/technical/api-config.html b/technical/api-config.html index 47b7b32..acfa981 100644 --- a/technical/api-config.html +++ b/technical/api-config.html
@@ -557,7 +557,7 @@ <div id="preamble"> <div class="sectionbody"> <div class="paragraph"><p>The config API gives callers a way to access git configuration files -(and files which have the same syntax). See <a href="git-config.html">git-config(1)</a> for a +(and files which have the same syntax). See <a href="../git-config.html">../git-config(1)</a> for a discussion of the config file syntax.</p></div> </div> </div> @@ -713,7 +713,7 @@ </dt> <dd> <p> -Similar to <tt>git_config_string</tt>, but expands <tt><sub></tt> or <tt></sub>user</tt> into the +Similar to <tt>git_config_string</tt>, but expands <tt>~</tt> or <tt>~user</tt> into the user’s home directory when found at the beginning of the path. </p> </dd> @@ -747,7 +747,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2012-02-23 14:45:28 PDT +Last updated 2012-06-07 13:15:22 PDT </div> </div> </body>
diff --git a/technical/api-config.txt b/technical/api-config.txt index edf8dfb..bd4d8b8 100644 --- a/technical/api-config.txt +++ b/technical/api-config.txt
@@ -2,7 +2,7 @@ ========== The config API gives callers a way to access git configuration files -(and files which have the same syntax). See linkgit:git-config[1] for a +(and files which have the same syntax). See linkgit:../git-config[1] for a discussion of the config file syntax. General Usage
diff --git a/technical/api-credentials.html b/technical/api-credentials.html index ab38b9d..01f09db 100644 --- a/technical/api-credentials.html +++ b/technical/api-credentials.html
@@ -560,10 +560,49 @@ password credentials from the user (even though credentials in the wider world can take many forms, in this document the word "credential" always refers to a username and password pair).</p></div> +<div class="paragraph"><p>This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below.</p></div> </div> </div> -<h2 id="_data_structures">Data Structures</h2> +<h2 id="_typical_setup">Typical setup</h2> <div class="sectionbody"> +<div class="listingblock"> +<div class="content"> +<pre><tt>+-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+</tt></pre> +</div></div> +<div class="paragraph"><p>The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password pair (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and does the actual authentication.</p></div> +</div> +<h2 id="_c_api">C API</h2> +<div class="sectionbody"> +<div class="paragraph"><p>The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage).</p></div> +<h3 id="_data_structures">Data Structures</h3><div style="clear:left"></div> <div class="dlist"><dl> <dt class="hdlist1"> <tt>struct credential</tt> @@ -585,9 +624,7 @@ <tt>credential_init</tt>.</p></div> </dd> </dl></div> -</div> -<h2 id="_functions">Functions</h2> -<div class="sectionbody"> +<h3 id="_functions">Functions</h3><div style="clear:left"></div> <div class="dlist"><dl> <dt class="hdlist1"> <tt>credential_init</tt> @@ -655,9 +692,7 @@ </p> </dd> </dl></div> -</div> -<h2 id="_example">Example</h2> -<div class="sectionbody"> +<h3 id="_example">Example</h3><div style="clear:left"></div> <div class="paragraph"><p>The example below shows how the functions of the credential API could be used to login to a fictitious "foo" service on a remote host:</p></div> <div class="listingblock"> @@ -716,8 +751,10 @@ credentials from and to long-term storage (where "long-term" is simply longer than a single git process; e.g., credentials may be stored in-memory for a few minutes, or indefinitely on disk).</p></div> -<div class="paragraph"><p>Each helper is specified by a single string. The string is transformed -by git into a command to be executed using these rules:</p></div> +<div class="paragraph"><p>Each helper is specified by a single string in the configuration +variable <tt>credential.helper</tt> (and others, see <a href="../git-config.html">../git-config(1)</a>). +The string is transformed by git into a command to be executed using +these rules:</p></div> <div class="olist arabic"><ol class="arabic"> <li> <p> @@ -863,11 +900,16 @@ request. This leaves room for future operations to be added (older helpers will just ignore the new requests).</p></div> </div> +<h2 id="_see_also">See also</h2> +<div class="sectionbody"> +<div class="paragraph"><p><a href="../gitcredentials.html">../gitcredentials(7)</a></p></div> +<div class="paragraph"><p><a href="../git-config.html">../git-config(5)</a> (See configuration variables <tt>credential.*</tt>)</p></div> +</div> </div> <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2011-12-21 14:30:17 PDT +Last updated 2012-06-07 13:15:22 PDT </div> </div> </body>
diff --git a/technical/api-credentials.txt b/technical/api-credentials.txt index 21ca6a2..199307c 100644 --- a/technical/api-credentials.txt +++ b/technical/api-credentials.txt
@@ -6,8 +6,52 @@ world can take many forms, in this document the word "credential" always refers to a username and password pair). +This document describes two interfaces: the C API that the credential +subsystem provides to the rest of git, and the protocol that git uses to +communicate with system-specific "credential helpers". If you are +writing git code that wants to look up or prompt for credentials, see +the section "C API" below. If you want to write your own helper, see +the section on "Credential Helpers" below. + +Typical setup +------------- + +------------ ++-----------------------+ +| git code (C) |--- to server requiring ---> +| | authentication +|.......................| +| C credential API |--- prompt ---> User ++-----------------------+ + ^ | + | pipe | + | v ++-----------------------+ +| git credential helper | ++-----------------------+ +------------ + +The git code (typically a remote-helper) will call the C API to obtain +credential data like a login/password pair (credential_fill). The +API will itself call a remote helper (e.g. "git credential-cache" or +"git credential-store") that may retrieve credential data from a +store. If the credential helper cannot find the information, the C API +will prompt the user. Then, the caller of the API takes care of +contacting the server, and does the actual authentication. + +C API +----- + +The credential C API is meant to be called by git code which needs to +acquire or store a credential. It is centered around an object +representing a single credential and provides three basic operations: +fill (acquire credentials by calling helpers and/or prompting the user), +approve (mark a credential as successfully used so that it can be stored +for later use), and reject (mark a credential as unsuccessful so that it +can be erased from any persistent storage). + Data Structures ---------------- +~~~~~~~~~~~~~~~ `struct credential`:: @@ -28,7 +72,7 @@ Functions ---------- +~~~~~~~~~ `credential_init`:: @@ -72,7 +116,7 @@ Parse a URL into broken-down credential fields. Example -------- +~~~~~~~ The example below shows how the functions of the credential API could be used to login to a fictitious "foo" service on a remote host: @@ -135,8 +179,10 @@ longer than a single git process; e.g., credentials may be stored in-memory for a few minutes, or indefinitely on disk). -Each helper is specified by a single string. The string is transformed -by git into a command to be executed using these rules: +Each helper is specified by a single string in the configuration +variable `credential.helper` (and others, see linkgit:../git-config[1]). +The string is transformed by git into a command to be executed using +these rules: 1. If the helper string begins with "!", it is considered a shell snippet, and everything after the "!" becomes the command. @@ -243,3 +289,10 @@ If a helper receives any other operation, it should silently ignore the request. This leaves room for future operations to be added (older helpers will just ignore the new requests). + +See also +-------- + +linkgit:../gitcredentials[7] + +linkgit:../git-config[5] (See configuration variables `credential.*`)
diff --git a/technical/api-merge.html b/technical/api-merge.html index e8d80da..9deb1d2 100644 --- a/technical/api-merge.html +++ b/technical/api-merge.html
@@ -615,7 +615,7 @@ ancestors in a recursive merge. If a helper program is specified by the <tt>[merge "<driver>"] recursive</tt> configuration, it will - be used (see <a href="gitattributes.html">gitattributes(5)</a>). + be used (see <a href="../gitattributes.html">../gitattributes(5)</a>). </p> </dd> <dt class="hdlist1"> @@ -741,7 +741,7 @@ <div id="footnotes"><hr /></div> <div id="footer"> <div id="footer-text"> -Last updated 2011-11-15 13:45:02 PDT +Last updated 2012-06-07 13:15:22 PDT </div> </div> </body>
diff --git a/technical/api-merge.txt b/technical/api-merge.txt index 9dc1bed..25158b8 100644 --- a/technical/api-merge.txt +++ b/technical/api-merge.txt
@@ -36,7 +36,7 @@ ancestors in a recursive merge. If a helper program is specified by the `[merge "<driver>"] recursive` configuration, it will - be used (see linkgit:gitattributes[5]). + be used (see linkgit:../gitattributes[5]). `variant`:: Resolve local conflicts automatically in favor
